home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / wtfor058.arc / WAITFOR.DOC < prev    next >
Text File  |  1990-10-05  |  20KB  |  524 lines
  1.  
  2.  
  3.  
  4.                                  Waitfor v0.58
  5.                                Copyright (c) 1990
  6.                               All Rights Reserved
  7.                            William H. Bond 1:325/118
  8.  
  9.  
  10.      This program is freely available for non-commercial use.  The only
  11.      thing I ask is that you let me know of any bugs, suggestions, etc..
  12.  
  13.  
  14.      Special thanks go to Ralf Brown for releasing DV-GLUE(c).  The
  15.      Desqview(tm) functions incorporated in this program came from this
  16.      library.  I'd also like to thank Don Dawson 1:141/730 and David Dyer-
  17.      Bennet 1:282/341 for their help in testing it and for making
  18.      suggestions that helped shape the program.
  19.  
  20.  
  21.      This program was developed using the following software: Qemm 5.0,
  22.      Desqview 2.26, MSC v6.0, DVGlue v1.01, MS-Dos 3.3.
  23.  
  24.  
  25.      This is a beta version.  There is no warranty expressed or implied.
  26.      The user of this program assumes all responsibility for the operation
  27.      of, and any consequences of using, this program.
  28.  
  29.  
  30.      Waitfor is a simple utility program for use with Desqview, mainly as a
  31.      batch file utility. It allows the user to synchronize events in
  32.      multiple windows by delaying the current process.  You can use it to
  33.      delay for a given amount of time, to allow a background process to
  34.      complete.  You can have it wait for a specific file to exist, and
  35.      optionally kill the file when it is found.  This can be used if a
  36.      background process creates a temporary file to signal that it has
  37.      completed a task.  It can also be made to wait for a specific file to
  38.      not exist, and optionally create the file if it doesn't exist.  You
  39.      can also specify the amount of available memory that needs to be free
  40.      before the program will exit.
  41.  
  42.  
  43.      By default Waitfor will exit as soon as the first condition becomes
  44.      true.  This behavior may be modified so as to wait for all exit
  45.      conditions to become true before exiting by using the -! or -& option.
  46.  
  47.  
  48.      Desqview named mailboxes are also supported in addition to files.  One
  49.      process may create or destroy a named mailbox to use as a semaphore
  50.      for other processes.  The other processes may test for the existence
  51.      or non existence of the named mailbox and wait accordingly.
  52.  
  53.  
  54.      Waitfor can also perform a simple test for existence of a file,
  55.      mailbox or specific amount of available memory and exit immediately
  56.      with an appropriate errorlevel.
  57.  
  58.  
  59.      While Waitfor is waiting for a condition to be met it will give up
  60.      almost all of it's timeslice back to Desqview.  This allows it to use
  61.      very little overhead while it is executing.  The amount of time it
  62.      gives back to Desqview is configurable.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      Syntax:
  71.  
  72.  
  73.      Waitfor   [-Ddelay] [-Ttimeout] [-!] [-&] [-Ffreememory] [-Ahh:mm:ss]
  74.                [-Efilename] [-Nfilename] [-k] [-c] [-Rretries] [-q]
  75.                [-MEmbxname] [-MNmbxname] [-mk] [-mc]
  76.                [-WEfilespec] [-WNfilespec]
  77.                [-MMmbxname] [-MDmbxname] [-XAmem] [-XFfile] [-XMmailbox]
  78.  
  79.  
  80.      -d = Delay for 'delay' 100ths seconds between loops.  While Waitfor is
  81.           executing it will by default 'sleep' for one second (-d100) after
  82.           checking for each exit condition.  This causes it to use very
  83.           little processor time while it is executing.  The -d option can
  84.           be used to vary this sleep time, though very little is gained by
  85.           increasing from the default.  Note that if you specify a delay of
  86.           1 minute (-d6000), that no exit conditions are checked during the
  87.           delay time.  The timeout value (if any) would also only be
  88.           updated on the screen once a minute.
  89.  
  90.  
  91.      -t = Wait for 'timeout' seconds before exit.  This can be combined
  92.           with the other options to avoid halting a process forever if the
  93.           background task hangs.  It can also be used as a simple countdown
  94.           timer.  If the -t option is the only one specified the program
  95.           will wait until the timeout counts down.  When combined with
  96.           other options the timeout will only count down while the other
  97.           conditions are false, when one of the other options (or all with
  98.           the -! option) become true the program will exit.  The timeout
  99.           value must be between 1 and 65535.  When the timeout is reached
  100.           Waitfor will exit with an errorlevel of 40.
  101.  
  102.  
  103.      -! = Will cause the program to wait for all exit conditions to be met
  104.           before exiting.  Normally the program will exit immediately when
  105.           any of the conditions are true.  If you are waiting for three
  106.           files to exist, the -! will cause an exit if all three have
  107.           existed during the execution of the program, they don't
  108.           necessarily have to exist at the same time.  The -t (timeout)
  109.           option is not affected by this option, a timeout will always
  110.           cause an immediate exit.  Waiting for multiple events will result
  111.           in an errorlevel corresponding to the last condition that became
  112.           true.
  113.  
  114.  
  115.      -& = Will cause the program to wait for all exit condition to be met
  116.           at the same time.  This is similar to the -! option, but has one
  117.           important difference.  If you are waiting for three files to
  118.           exist, the -& option will cause an exit only when all three files
  119.           exist at the same time.  The -t (timeout) option is not affected
  120.           by this option, a timeout will always cause an immediate exit.
  121.           Waiting for multiple events will result in an errorlevel
  122.           corresponding to the last condition that became true.
  123.  
  124.           The -& option also will change the look of program output.  Each
  125.           condition specified will be displayed on the screen.  The program
  126.           will then display a '-' or 'y' for each option depending on
  127.           whether or not the condition is true.
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      -f = Do not exit until 'freememory' free memory (in K) exists.  This
  137.           may be used by itself or in combination with other options.  If
  138.           used with other options you also need to use the -! option, this
  139.           will prevent an immediate exit if one of the other option(s)
  140.           become true, and allow the free memory to be checked.  It checks
  141.           the largest available conventional or expanded memory area (as
  142.           shown by Memory Services) if either is larger than the specified
  143.           amount the program will be allowed to exit.
  144.  
  145.  
  146.      -a = Wait until the time specified as 'hh:mm:ss'.  The time must be
  147.           specified in 24 hour format.  Unlike the -t timeout option this
  148.           one does not force an unconditional exit when the time is
  149.           reached.  The format is hh:mm:ss, hh:mm, or hh.
  150.  
  151.  
  152.      -e = Wait for the file 'filename' to exist.  This can be used to halt
  153.           the current process until a background process creates a specific
  154.           file.  More than one file may be specified (up to 10) by using
  155.           the -e option multiple times.  As soon as the first file is found
  156.           Waitfor will exit with an errorlevel of 10 (this behavior may be
  157.           modified by the -! option).
  158.  
  159.  
  160.      -n = Wait for the file 'filename' to not exist.  This will wait for
  161.           the specified file to disappear.  You could have a process create
  162.           a temporary file while it is running and delete the file when the
  163.           job is complete.  Any other task can check for the existence of
  164.           the file and wait until the file doesn't exist.  More than one
  165.           file may be specified (up to 10) by using the -n option multiple
  166.           times.  As soon as any specified file is found not to exist,
  167.           Waitfor will exit with an errorlevel of 11 (this behavior may be
  168.           modified by the -! option).
  169.  
  170.  
  171.      -k = Kill the 'filename' specified by the -e option before exiting.
  172.           By default the file is left intact after it is found to exist.
  173.           No specific errorlevel is generated.  See note below.
  174.  
  175.  
  176.      -c = Create the file specified by the -n option if it doesn't exist.
  177.           This will first check for the existence of the -n filename, if
  178.           the file exists it will wait as usual.  If the file doesn't exist
  179.           it will be created (0 length) and the -n checking for that file
  180.           will be disabled immediately.  If the -n option is used in a
  181.           batch file along with the -c option, it will prevent the batch
  182.           file from being executed by two tasks at the same time.  The
  183.           batch file should delete the -n file just before it ends.  No
  184.           specific errorlevel is generated.
  185.  
  186.  
  187.      -r = Specify retry count for the -e and -k combination.  This may be
  188.           used to modify the default retry value of 3 when combining the -e
  189.           and -k options.  See notes section for description of potential
  190.           problems if SHARE is not loaded.
  191.  
  192.  
  193.      -q = Suppress copyright display.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      The -m? options are similar to the above file options except they use
  203.      a Desqview global named mailbox instead of a filename.  The mailbox is
  204.      visible in all windows.  It will exist until the mailbox is killed, or
  205.      the window in which it was created is closed.
  206.  
  207.  
  208.      -me = Wait for the specified mailbox 'mbxname' to exist.  More than
  209.           one mailbox may be specified (up to 10) by using the -me option
  210.           multiple times.  When the first mailbox is found Waitfor will
  211.           exit with an errorlevel of 20 (this behavior may be modified with
  212.           the -! option).
  213.  
  214.  
  215.      -mn = Wait for the specified mailbox 'mbxname' to not exist.  More
  216.           than one mailbox may be specified (up to 10) by using the -mn
  217.           option multiple times.  When any mailbox is found to no longer
  218.           exist Waitfor will exit with an errorlevel of 21 (this behavior
  219.           may be modified with the -! option).
  220.  
  221.  
  222.      -mk = Kill the mailbox specified by the -me option when it is found to
  223.           exist.  This releases the mailboxes' memory back to Desqview.  No
  224.           specific errorlevel is generated.
  225.  
  226.  
  227.      -mc = Create the mailbox specified in the -mn option if it doesn't
  228.           exist.  Each mailbox created uses some of the Common Memory as
  229.           shown in the Memory Services program.  No specific errorlevel is
  230.           generated.
  231.  
  232.  
  233.      -mm =  Create a mailbox named 'mbxname'.  This option will create the
  234.           mailbox regardless of what other options are specified.  If the
  235.           mailbox already exists the option is ignored.  No specific
  236.           errorlevel is generated.
  237.  
  238.  
  239.      -md = Destroy the mailbox names 'mbxname'.  This option also ignores
  240.           any other options that may have been specified.  If the mailbox
  241.           doesn't exist the option is ignored.  No specific errorlevel is
  242.           generated.
  243.  
  244.  
  245.      -we = Wait for the wildcard 'filespec' to exist.  The filespec is
  246.           passed on to the DOS find first function exactly as specified.
  247.           More than one wildcard may be specified (up to 10) by using the
  248.           -we option multiple times.  Any file matching the filespec will
  249.           cause an exit with an errorlevel of 30 (this behavior may be
  250.           modified with the -! option).
  251.  
  252.  
  253.      -wn = Wait for the wildcard 'filespec' to not exist.  The filespec is
  254.           passed on to the DOS find first function exactly as specified.
  255.           More than one wildcard may be specified (up to 10) by using the
  256.           -wn option multiple times.  When no file matching the filespec is
  257.           found, Waitfor will exit with an errorlevel of 31 (this behavior
  258.           may be modified with the -! option).
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      -xa = Check for 'mem' (in K) available conventional or expanded memory
  269.           and exit immediately.  Any other options are ignored.  If 'mem'
  270.           available memory exists Waitfor will exit with an errorlevel of
  271.           35, otherwise it will exit with an errorlevel of 36.
  272.  
  273.  
  274.      -xf = Test for the existence of the file 'file' and exit immediately.
  275.           Any other options are ignored.  The errorlevel is set to 15 if
  276.           the file exists and 16 if the file doesn't exist.
  277.  
  278.  
  279.      -xm = Test for the existence of the named mailbox 'mailbox' and exit
  280.           immediately.  Any other options are ignored.  The errorlevel is
  281.           set to 25 if the mailbox exists and 26 if the mailbox doesn't
  282.           exist.
  283.  
  284.  
  285.  
  286.      Notes:
  287.  
  288.  
  289.      Executing Waitfor without any options will display a short help
  290.      screen.
  291.  
  292.      The options may be combined and are not case sensitive.  You could
  293.      have the program wait for one file to exist while waiting for another
  294.      file to not exist, and specify a timeout at the same time.
  295.  
  296.      Filename arguments may contain drive and/or path specifications.
  297.  
  298.      Pressing escape or Control-C/Break will end the program with an
  299.      errorlevel of 50.  Pressing 'C' or 'c' will end the program with an
  300.      errorlevel of 5.
  301.  
  302.      Note that there are no spaces between the switch and the switch
  303.      argument.  A '/' character may be used instead of the '-' character.
  304.  
  305.      If the -c, -k, -mc, -mk options are used with multiple file names or
  306.      mailboxes, all files/mailboxes will be affected.
  307.  
  308.      One suggestion for file names is DESQTMP?.???, check the Desqview
  309.      manual for details.
  310.  
  311.  
  312.  
  313.      If SHARE.EXE is not loaded there is a potential problem using the -e
  314.      and -k options together.  The problem occurs if Waitfor is waiting for
  315.      the specified file (-e) and the file is created by another process and
  316.      not immediately closed.  In this case Waitfor will delete the file,
  317.      but the other process may still be writing to it.  If SHARE is loaded
  318.      Waitfor will detect this condition and abort with an errorlevel of 52
  319.      if it cannot delete the file after 3 retries, with a delay (-d value
  320.      or the default of 1 second) between retries.  This retry value may be
  321.      modified by using the -r option.  If you're only creating 0 length
  322.      semaphore files (eg: rem >testfile) this should not present a problem.
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.      Examples:
  335.  
  336.  
  337.      start of MAIN.BAT
  338.      Waitfor -nc:\bbs\batch.flg -c
  339.      ... do some non reentrant stuff here.
  340.      if exist c:\bbs\batch.flg del c:\bbs\batch.flg
  341.      end of MAIN.BAT
  342.  
  343.      When the above is executed there are two cases to consider:
  344.  
  345.      1.  If c:\bbs\batch.flg exists the execution of MAIN.BAT will be
  346.      suspended until MAIN.BAT is finished processing and deletes
  347.      c:\bbs\batch.flg.
  348.  
  349.      2.  If c:\bbs\batch.flg does not exist it will be created and
  350.      execution of MAIN.BAT will continue immediately.  If a second copy of
  351.      MAIN.BAT starts executing concurrently it will be suspended as in case
  352.      1 above.
  353.  
  354.  
  355.      Waitfor -t60
  356.      Wait for 1 minute (60 sec.).
  357.  
  358.  
  359.      Waitfor -ewait.fil
  360.      Wait for the file 'wait.fil' to exist.
  361.  
  362.  
  363.      Waitfor -ewait.fil -k -t3600
  364.      Wait for the file 'wait.fil' to exist or 1 hour, whichever comes
  365.      first.  The file will be deleted when found, unless the timeout is
  366.      reached first.
  367.  
  368.  
  369.      Waitfor -meflag
  370.      Wait for the a mailbox named 'flag' to exist.
  371.  
  372.  
  373.      Waitfor -mmflag
  374.      This will simply create a mailbox named 'flag'.
  375.  
  376.  
  377.      Waitfor -xftest.fil
  378.      Test for the existence of 'test.fil' and exit immediately.
  379.  
  380.  
  381.      Waitfor -eflag1 -eflag2 -eflag3
  382.      Exit as soon as any one of the three files are found.
  383.  
  384.  
  385.      Waitfor -eflag1 -eflag2 -eflag3 -!
  386.      Do not exit until all three files are found.
  387.  
  388.  
  389.      Waitfor -nflag1 -nflag2 -nflag3
  390.      Exit as soon as any one of the three files do not exist.
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.      Waitfor -nflag1 -nflag2 -nflag3 -!
  401.      Do not exit until all three files do not exist.
  402.  
  403.  
  404.      Waitfor -efile1 -efile2 -efile3 -k -!
  405.      Wait for all three files to exist and kill each as they are found.
  406.  
  407.  
  408.      Waitfor -f384
  409.      Wait for at least 384k free conventional or expanded memory.
  410.  
  411.  
  412.      Waitfor -efile1 -f520 -!
  413.      Wait for file1 to exist, then don't exit until there is at least 520k
  414.      free memory.
  415.  
  416.  
  417.      Waitfor -xa420
  418.      Test for at least 420k available memory and exit immediately.
  419.  
  420.  
  421.      Waitfor -a5:00
  422.      Wait until 5:00am, then exit.
  423.  
  424.  
  425.      Waitfor -wed:\tossdir\*.*
  426.      Wait until any file exists in the 'd:\tossdir' directory.
  427.  
  428.  
  429.      Waitfor -wnd:\tossdir\*.*
  430.      Wait until the 'd:\tossdir' directory is emtpy.
  431.  
  432.  
  433.  
  434.      Order of exit condition evaluation:
  435.  
  436.      1.  -xa available memory check, exit immediately
  437.      2.  -xf file test, exit immediately
  438.      3.  -xm mailbox test, exit immediately
  439.      4.  escape key or 'c' key
  440.      5.  -t timeout
  441.      6   -a specific time
  442.      7.  -e existence of a file
  443.      8.  -n non existence of a file
  444.      9.  -me existence of a mailbox
  445.      10. -mn non existence of a mailbox
  446.      11. -we existence if a wildcard
  447.      12. -wn non existence of a wildcard
  448.      13. -f available memory check
  449.  
  450.      Whichever condition becomes true first will cause the program to exit
  451.      with the corresponding errorlevel, unless the -! or -& option is also
  452.      given.  Exit condition checking is only enabled for options specified
  453.      on the command line.
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.      Option Summary:
  467.  
  468.      -d  = sleep for 'delay' 100ths seconds between loops, default 100.
  469.      -t  = wait for 'timeout' seconds.
  470.      -!  = Wait for multiple exit conditions to be met before exiting.
  471.      -&  = Wait for all exit conditions to be met at the same time.
  472.      -f  = Do not exit until 'freememory' (in K) free memory exists.
  473.      -a  = Wait until the time specified as 'hh:mm:ss'.
  474.      -e  = wait for 'filename' to exist.
  475.      -n  = wait for 'filename' to not exist.
  476.      -k  = kill 'filename' when found, use with -e.
  477.      -c  = create 'filename' if it does not exist, use with -n.
  478.      -r  = specify retry count for -e and -k combination.
  479.      -q  = disable copyright display.
  480.      -me = wait for mailbox 'mbxname' to exist.
  481.      -mn = wait for mailbox 'mbxname' to not exist.
  482.      -mk = kill mailbox 'mbxname' when found, use with -me.
  483.      -mc = create mailbox 'mbxname' if it does not exist, use with -mn.
  484.      -mm = create a mailbox named 'mbxname', unconditional.
  485.      -md = destroy a mailbox named 'mbxname', unconditional.
  486.      -we = wait until the wildcard 'filespec' exists.
  487.      -wn = wait until the wildcard 'filespec' does not exist.
  488.      -xa = test for 'mem' available memory.
  489.      -xf = test 'filename' for existence.
  490.      -xm = test 'mbxname' for existence.
  491.  
  492.  
  493.  
  494.      Errorlevel summary (most are also displayed on the usage screen):
  495.  
  496.      0  = -mm or -md options created or destroyed a mailbox and no other
  497.           options were specified.  -f option was the only one specified.
  498.      1  = -a time reached first
  499.      5  = 'c' continue key.
  500.      10 = -e file found first.
  501.      11 = -n file found not to exist first.
  502.      15 = -xf file exists.
  503.      16 = -xf file doesn't exist.
  504.      20 = -me mailbox found first.
  505.      21 = -mn mailbox not found first.
  506.      25 = -xm mailbox exists.
  507.      26 = -xm mailbox doesn't exist.
  508.      30 = -we wildcard exists.
  509.      31 = -wn wildcard does not exist.
  510.      35 = -xa memory is available.
  511.      36 = -xa memory is not available.
  512.      40 = Timeout value reached first.
  513.      50 = Escape or Ctrl-C.
  514.      51 = Command line or syntax error.
  515.      52 = File sharing error when -e and -k options are used.
  516.      55 = Fatal error, cannot create file or cannot delete file, or cannot
  517.           create mailbox.
  518.  
  519.  
  520.      Any bugs reports, comments or suggestions may be directed to Bill Bond
  521.      at 1:325/118@FidoNet.
  522.  
  523.      Desqview is a trademark of Quarterdeck Office Systems.
  524.